@davidkyle make contrib is not happy:

Error: The property 'deployment_id' does not exist in the rest-api-spec ml.stop_trained_model_deployment url template
At: /Users/dolaru/workspace/elasticsearch-specification/specification/ml/stop_trained_model_deployment/MlStopTrainedModelDeploymentRequest.ts:30:47

29   */
30  export interface Request extends RequestBase {
31    path_parts: {
32      /**
33       * The unique identifier for the deployment of the model.
34       */
35      deployment_id: Id
36    }
37    query_parameters: {
38      /**

Looks like the JSON spec is not up to date and I don't know what's the proper way to update it. 😞

Hey @dolaru, the check is complaining that https://github.com/elastic/elasticsearch/blob/main/rest-api-spec/src/main/resources/rest-api-spec/api/ml.stop_trained_model_deployment.json does not contain deployment_id. I believe model_id should be changed to deployment_id there first?

I'm also wondering if the same applies to ml.start_trained_model_deployment, but in that case there is a deployment_id described as "The Id of the new deployment. Defaults to the model_id if not set.".

the check is complaining that https://github.com/elastic/elasticsearch/blob/main/rest-api-spec/src/main/resources/rest-api-spec/api/ml.stop_trained_model_deployment.json does not contain deployment_id. I believe model_id should be changed to deployment_id there first?

@davidkyle can I leave this with you please?

I'm also wondering if the same applies to ml.start_trained_model_deployment

@pquentin for the _start API, model_id is a required path parameter and deployment_id is an optional query parameter that can be used if multiple deployments from the same trained model are required. For example:

# Two separate deployments of the ELSER v2 model
POST _ml/trained_models/.elser_model_2/deployment/_start?deployment_id=elser_main
POST _ml/trained_models/.elser_model_2/deployment/_start?deployment_id=elser_secondary

For the _stop API, the path parameter should be deployment_id since it targets a trained model deployment, not a model definition. This will introduce a breaking change in clients since the named model_id parameter would no longer be accepted - I think it's something we'll have to live with.

For the _stop API, the path parameter should be deployment_id

This is correct but if renaming the path parameter breaks the client I think we should rely on documentation to state it should be the deployment Id. @pquentin is it possible to deprecate the model_id usage and add a param deployment_id?

The change to the start deployment API is good and necessary as without it a user cannot deploy a model multiple times.

@dolaru do you want to take the Stop API change out of this PR and just merge the Start API change? That way we have made some progress while we figure out the stop issue.

take the Stop API change out of this PR

Done ✅

I don't know why the elasticsearch-serverless-openapi.json change has appeared in this PR

Probably because I didn't run make contrib on the vocabulary scores PR. 😅
I'll take that out since it's not related to this PR.

Following you can find the validation results for the API you have changed.

You can validate this API yourself by using the make validate target.